<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Communicating between Replication Manager Sites</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="rep.html" title="Chapter 13.  Berkeley DB Replication" />
    <link rel="prev" href="rep_clock_skew.html" title="Clock skew" />
    <link rel="next" href="rep_twosite.html" title="Special considerations for two-site replication groups" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Communicating between Replication Manager Sites</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="rep_clock_skew.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 13.  Berkeley DB Replication </th>
          <td width="20%" align="right"> <a accesskey="n" href="rep_twosite.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="comm_repsites"></a>Communicating between Replication Manager Sites</h2>
          </div>
        </div>
      </div>
      <div class="toc">
        <dl>
          <dt>
            <span class="sect2">
              <a href="comm_repsites.html#conf_writeforw">Configuring for Write Forwarding</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="comm_repsites.html#repmgr_channels">Using Replication Manager message channels</a>
            </span>
          </dt>
        </dl>
      </div>
      <p>
       Replication Manager provides all of the communications between sites needed for
       an application that performs all of its write operations on the master site and
       only performs read operations on client sites.
    </p>
      <p>
       For applications with a simple data and transaction model, Replication Manager
       also provides automatic write forwarding as a configurable option. When write
       forwarding is configured, some write operations can be performed on clients.
       In addition, an application can use Replication Manager message channels to
       send its own messages to other sites in the replication group using Replication
       Manager's internal communications infrastructure.
    </p>
      <p>
        These approaches are described in the following sections.
    </p>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="conf_writeforw"></a>Configuring for Write Forwarding</h3>
            </div>
          </div>
        </div>
        <p>
       By default, write operations cannot be performed on a
       replication client site. Replication Manager provides a configurable
       option that allows forwarding of simple client put and delete 
       operations to the master site for processing. These operations must 
       use an implicit NULL transaction ID to be forwarded. Any other write
       operation that specifies a non-NULL transaction or uses a cursor 
       returns an error. This option is turned off by default. 
    </p>
        <p>
       To configure write forwarding, use
       <code class="function">rep_set_config</code> with the
       <code class="literal">DB_REPMGR_CONF_FORWARD_WRITES</code> option. 
       (See the <a href="../api_reference/C/repconfig.html#config_DB_REPMGR_CONF_FORWARD_WRITES" class="olink">
       DB_REPMGR_CONF_FORWARD_WRITES</a> section in the <em class="citetitle">Berkeley DB C API Reference Guide</em>
       for more information.) 
    </p>
        <p>
       The master must have an open database handle for the database
       on which a forwarded write operation is being performed.
       All sites in the replication group should have the same value 
       for this configuration option. 
    </p>
        <p>
       The following restrictions apply to the use of write forwarding:
    </p>
        <div class="itemizedlist">
          <ul type="disc">
            <li>
              <p>
                    The application cannot use Replication Manager message channels for any other purpose.
                </p>
            </li>
            <li>
              <p>
                    All sites in the replication group must be on platforms of the same endianness.
                </p>
            </li>
            <li>
              <p>
                    Use of write forwarding is not supported with BDB SQL HA.
                </p>
            </li>
            <li>
              <p>
                    Write forwarding cannot be performed on databases using callbacks 
                    or values that must be supplied for each <code class="methodname">DbEnv::open()</code>
                    call to avoid database corruption. Examples include the callbacks or
                    values defined by the <code class="methodname">DB-&gt;set_dup_compare()</code>,
                    <code class="methodname">DB-&gt;set_bt_compare()</code>,
                    <code class="methodname">DB-&gt;set_hash()</code> and 
                    <code class="methodname">DB-&gt;set_heapsize() methods</code>.
                </p>
            </li>
            <li>
              <p>
                    Write forwarding cannot be performed on a partitioned database.
                </p>
            </li>
            <li>
              <p>
                    Bulk put and del operations using <code class="literal">DB_MULTIPLE</code> or
                    <code class="literal">DB_MULTIPLE_KEY</code> flags are not supported. 
                </p>
            </li>
          </ul>
        </div>
        <p>
       For more information, see <em class="citetitle">Berkeley DB Getting Started with Replicated Applications</em>.
    </p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="repmgr_channels"></a>Using Replication Manager message channels</h3>
            </div>
          </div>
        </div>
        <p> 
        The various sites comprising a replication group frequently
        need to communicate with one another. Mostly, these messages
        are handled for you internally by the Replication Manager.
        However, your application may have a requirement to pass
        messages beyond what the Replication Manager requires in order
        to satisfy its own internal workings. 
    </p>
        <p>
        For this reason, you can access and use the Replication
        Manager's internal message channels. You do this by using the
        <code class="literal">DB_CHANNEL</code> class, and by implementing a
        message handling function on each of your sites. 
    </p>
        <p> 
        Note that an example of using Replication Manager message
        channels is available in the distribution. See <a class="xref" href="rep_ex_chan.html" title="Ex_rep_chan: a Replication Manager channel example">Ex_rep_chan: a Replication Manager channel example</a> for
        more information. 
    </p>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="dbchannel_class"></a>DB_CHANNEL</h4>
              </div>
            </div>
          </div>
          <p>
            The <code class="literal">DB_CHANNEL</code> class provides a
            series of methods which allow you to send messages to the
            other sites in your replication group. You create a
            <code class="literal">DB_CHANNEL</code> handle using the
            <a href="../api_reference/C/repmgr_channel.html" class="olink">DB_ENV-&gt;repmgr_channel()</a> method. When you are done with the
            handle, close it using the <a href="../api_reference/C/dbchannel_close.html" class="olink">DB_CHANNEL-&gt;close()</a> method. A
            closed handle must never be accessed again. Note that all
            channel handles should be closed before the associated
            environment handle is closed. Also, allow all message
            operations to complete on the channel before closing the
            handle. 
        </p>
          <p>
            When you create a <code class="literal">DB_CHANNEL</code> handle,
            you indicate what channel you want to use. Possibilities
            are:
        </p>
          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p>
                    The numerical env ID of a remote site in the
                    replication group. 
                </p>
              </li>
              <li>
                <p>
                    <code class="literal">DB_EID_MASTER</code>
                </p>
                <p> 
                    Messages sent on this channel are sent only to
                    the master site. Note that messages are always
                    sent to the current master, even if the master has
                    changed since the channel was opened. 
                </p>
                <p> 
                    If the local site is the master, then sending
                    messages on this channel will result in the local
                    site receiving those messages echoed back to
                    itself.
                </p>
              </li>
            </ul>
          </div>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="dbchannel_send"></a>Sending messages over a message channel</h4>
              </div>
            </div>
          </div>
          <p> 
            You can send any message you want over a message
            channel. The message can be as simple as a character
            string and as complex as a large data structure. However,
            before you can send the message, you must encapsulate it
            within one or more <a href="../api_reference/C/dbt.html" class="olink">DBT</a>s. This means <a class="link" href="am_misc_struct.html" title="Storing C/C++ structures/objects">marshaling the message</a>
            if it is contained within a complex data structure. </p>
          <p> 
            The methods that you use to send messages all accept an
            array of <a href="../api_reference/C/dbt.html" class="olink">DBT</a>s. This means that in most circumstances it
            is perfectly acceptable to send multi-part messages.
        </p>
          <p>
            Messages may be sent either asynchronously or
            synchronously. To send a message asynchronously, use the
            <a href="../api_reference/C/dbchannel_send_msg.html" class="olink">DB_CHANNEL-&gt;send_msg()</a> method. This method sends its message
            and then immediately returns without waiting for any sort
            of a response. 
            
        </p>
          <p>
            To send a message synchronously, use the
            <a href="../api_reference/C/dbchannel_send_request.html" class="olink">DB_CHANNEL-&gt;send_request()</a> method. This method blocks until
            it receives a response from the site to which it sent the
            message (or until a timeout threshold is reached).
            
        </p>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="dbchannel_respond"></a>Message Responses</h4>
              </div>
            </div>
          </div>
          <p>
                Message responses are required if a message is sent
                on a channel using the <a href="../api_reference/C/dbchannel_send_request.html" class="olink">DB_CHANNEL-&gt;send_request()</a>
                method. That method accepts the address of a single
                <a href="../api_reference/C/dbt.html" class="olink">DBT</a> which is used to receive the response from the
                remote site. 
            </p>
          <p>
                Message responses are encapsulated in a single
                <a href="../api_reference/C/dbt.html" class="olink">DBT</a>. The response can be anything from a complex
                data structure, to a string, to a simple type, to no
                information at all. In the latter case, receipt of the
                <a href="../api_reference/C/dbt.html" class="olink">DBT</a> is sufficient to indicate that the request was
                received at the remote site. 
            </p>
          <p> Responses are sent back from the remote system
                using its message handling function. Usually that
                function calls <a href="../api_reference/C/dbchannel_send_msg.html" class="olink">DB_CHANNEL-&gt;send_msg()</a> to send a single
                response. </p>
          <p> 
                The response must be contained in a single <a href="../api_reference/C/dbt.html" class="olink">DBT</a>.
                If a multi-part response is required by the
                application, you can configure the response <a href="../api_reference/C/dbt.html" class="olink">DBT</a> that
                you provide to <a href="../api_reference/C/dbchannel_send_request.html" class="olink">DB_CHANNEL-&gt;send_request()</a> for <a class="link" href="am_misc_bulk.html" title="Retrieving and updating records in bulk">bulk operations</a>.
            </p>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="dbchannel_receive"></a>Receiving messages</h4>
              </div>
            </div>
          </div>
          <p>
            Messages received at a remote site are handled using a
            callback function. This function is configured for the
            local environment using the <a href="../api_reference/C/repmgr_msg_dispatch.html" class="olink">DB_ENV-&gt;repmgr_msg_dispatch()</a>
            method. For best results, the message dispatch function
            should be configured for the local environment before
            replication is started. In this way, you do not run the
            risk of missing messages sent after replication has
            started but before the message dispatch function is
            configured for the environment.
        </p>
          <p>
            The callback configured by <a href="../api_reference/C/repmgr_msg_dispatch.html" class="olink">DB_ENV-&gt;repmgr_msg_dispatch()</a>
            accepts four parameters of note: 
        </p>
          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p> 
                    A response channel. This is the channel the
                    function will use to respond to the message, if a
                    response is required. To respond to the message,
                    the function uses the <a href="../api_reference/C/dbchannel_send_msg.html" class="olink">DB_CHANNEL-&gt;send_msg()</a> method.
                </p>
              </li>
              <li>
                <p>
                    An array of <a href="../api_reference/C/dbt.html" class="olink">DBT</a>s. These hold the message that
                    this function must handle.
                </p>
              </li>
              <li>
                <p>
                    A numerical value that indicates how many
                    elements the previously described array holds.
                </p>
              </li>
              <li>
                <p> 
                    A flag that indicates whether the message
                    requires a response. If the flag is set to
                    <code class="literal">DB_REPMGR_NEED_RESPONSE</code>,
                    then the function should send a single <a href="../api_reference/C/dbt.html" class="olink">DBT</a> in
                    response using the channel provided to this
                    function, and the <a href="../api_reference/C/dbchannel_send_msg.html" class="olink">DB_CHANNEL-&gt;send_msg()</a> method.
                </p>
              </li>
            </ul>
          </div>
          <p> 
            For an example of using this callback, see the
            <code class="literal">operation_dispatch()</code> function,
            which is available with the <a class="link" href="rep_ex_chan.html" title="Ex_rep_chan: a Replication Manager channel example">
            ex_rep_chan example</a> in your product
            distribution.
        </p>
        </div>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="rep_clock_skew.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="rep.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="rep_twosite.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Clock skew </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Special considerations for two-site replication groups</td>
        </tr>
      </table>
    </div>
  </body>
</html>
